'\"macro stdmacro
.\"
.\" Copyright (C) 2017-2019 Marko Myllynen <myllynen@redhat.com>
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\"
.TH PMDABCC 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmdabcc\f1 \- BCC PMDA
.SH DESCRIPTION
\fBpmdabcc\fP is a Performance Co-Pilot (PCP) Performance Metrics Domain
Agent (PMDA) which extracts live performance data from extended BPF
(Berkeley Packet Filter) in-kernel programs by using BCC (BPF Compiler
Collection) Python frontend.
.PP
\fBpmdabcc\fP loads and acts as a bridge for any number of configured,
separate PCP BCC PMDA Python modules running BPF programs.
Existing BCC Python tools and programs should be possible to be utilized
with PCP BCC PMDA modules with reasonable effort.
.PP
See the BPF and BCC documentation for detailed description of both.
.SH CONFIGURATION
\fBpmdabcc\fP reads a mandatory ini-style configuration file:
.IP
.PD 0
.IP
.I \f(CW$PCP_PMDAS_DIR\fP/bcc/bcc.conf
.PD
.PP
This file must contain a \fB[pmda]\fP section.
The following PMDA options are available
(their default values are shown in parenthesis),
options marked with asterisk (\fB*\fP)
can be overridden in module-specific configuration sections:
.TP 15
.B modules \fR(unset)\fP
The \fBpmdabcc\fP PMDA reads module-specific configuration for each
module listed in the comma-separated list of \fBmodules\fP (mandatory).
.TP
.B prefix \fR(\fP\fIbcc.\fP\fR)\fP *
By default, all metrics from the modules will appear under the \fIbcc\fP
Performance Metrics Name Space (PMNS) tree, \fBprefix\fP (optional) can be
used to change this generic prefix.
.TP
.B process_refresh \fR(\fP\fI0\fP\fR)\fP
See below.
.TP
.B module_failure_fatal \fR(\fP\fITrue\fP\fR)\fP
A boolean value for \fBmodule_failure_fatal\fP (optional) controls whether
a module failing to compile should cause the whole PMDA to abort (this
is the default) or to start up with possibly remaining functional modules.
Module configuration errors and internal errors (such as failing to
register the provided PMNS metrics, see \fBPMNS\fP(5))
will always cause the PMDA to fail.
.PP
Of particular note, the \fBprocess\fP option accepted by some modules
evalutes the given PIDs and process names at PMDA/module initialization
time and apply filtering for only those processes found at that stage.
This is due to fact that the in-kernel BPF program is compiled at module
initialization time and, even more importantly, they are often running
at performance critical areas where it is not acceptable to do process
name lookups each time a request is processed by the BPF program.
To allow modules to monitor named processes (say, \fBprocess = java\fP)
even if they restart the \fBprocess_refresh\fP should be set to a
non-negative integer \fIN\fP to dynamically refresh monitored processes
every \fIN\fP seconds.
In case new processes matching the process filter have appeared, the
currently running BPF is detached and a new BPF program with updated PID
information is installed (and if no PIDs matching the filter are anymore
present, the BPF program will be detach to avoid any needless overhead).
.PP
For each \fImodule\fP listed in \fBmodules\fP a corresponding \fI[module]\fP
section must be defined containing at least the following options:
.TP 15
.B module
Defines the actual Python module file name to be loaded during
PMDA startup under the \fImodules\fP subdirectory of the PCP BCC PMDA
installation.
.TP
.B cluster
Specifies the unique cluster ID (see \fBPMNS\fP(5)) for the metrics
provided by the module under the PMNS path.
.PP
All modules accept but not necessarily use the boolean \fBdebug\fP option.
.PP
Modules may also support additional module-specific configuration options,
refer to the default configuration file for their supported options.
.SH INSTALLATION
To install, the following must be done as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/bcc
# ./Install
.fi
.ft P
.RE
.sp 1
To uninstall, the following must be done as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/bcc
# ./Remove
.fi
.ft P
.RE
.sp 1
\fBpmdabcc\fP is launched by \fBpmcd\fP(1) and should never be
executed directly.
The \fBInstall\fP and \fBRemove\fP scripts notify \fBpmcd\fP(1) when
the agent is installed or removed.
.PP
In case \fBmodule_failure_fatal\fP is set to \fBFalse\fP, the PMDA
installation will be considered successful even if some or even all
configured modules fail to load, in such cases metric values provided
by the failing modules will not be available.
The \fBpmdabcc\fP agent log file (see below) will contain detailed
information about activation of each module.
.PP
Some modules will start providing values only after having collected data
from related system activity.
For instance, the \fBtcpperpid\fP module will not provide any values unless
there are processes generating TCP traffic on the system.
.SH FILES
.TP 5
.I \f(CW$PCP_PMDAS_DIR\fP/bcc/bcc.conf
configuration file for the \fBpmdabcc\fP agent
.TP
.I \f(CW$PCP_PMDAS_DIR\fP/bcc/modules/*.{py,python}
PCP BCC PMDA Python modules available for the \fBpmdabcc\fP agent
.TP
.I \f(CW$PCP_PMDAS_DIR\fP/bcc/Install
installation script for the \fBpmdabcc\fP agent
.TP
.I \f(CW$PCP_PMDAS_DIR\fP/bcc/Remove\fP
undo installation script for the \fBpmdabcc\fP agent
.TP
.I \f(CW$PCP_LOG_DIR\fP/pmcd/bcc.log
default log file for messages from the \fBpmdabcc\fP agent
.PP
Note that the usual/default value for \fB$PCP_PMDAS_DIR\fP is
.B /var/lib/pcp/pmdas
and the default for \fB$PCP_LOG_DIR\fP is
.B /var/log/pcp
but these settings are platform dependent.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR PCPIntro (1),
.BR bcc (1),
.BR bpf (1)
and
.BR pmcd (1).
